advice: recommend GIT_ADVICE=0 for tools #1781

derrickstolee · 2024-09-05T15:44:59Z

I'm finally getting around to this doc update that I promised [1] a few weeks ago.

[1] https://lore.kernel.org/git/[email protected]/

Thanks, -Stolee

cc: [email protected]
cc: [email protected]
cc: [email protected]
cc: [email protected]
cc: Jeff King [email protected]
cc: Gabor Gombas [email protected]
cc: Eric Sunshine [email protected]

derrickstolee · 2024-09-05T17:58:32Z

/submit

gitgitgadget · 2024-09-05T17:59:20Z

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1781/derrickstolee/advice-docs-v1

To fetch this version to local tag pr-1781/derrickstolee/advice-docs-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1781/derrickstolee/advice-docs-v1

gitgitgadget · 2024-09-05T18:05:52Z

On the Git mailing list, Eric Sunshine wrote (reply to this):

On Thu, Sep 5, 2024 at 1:59 PM Derrick Stolee via GitGitGadget
<[email protected]> wrote:
> The GIT_ADVICE environment variable was added implicitly in b79deeb5544
> (advice: add --no-advice global option, 2024-05-03) but was not
> documented. Add documentation to show that it is an option for tools
> that want to disable these messages. Make note that while the
> --no-advice option exists, older Git versions will fail to parse that
> option. The environment variable presents a way to change the behavior
> of Git versions that understand it without disrupting older versions.
>
> Signed-off-by: Derrick Stolee <[email protected]>
> ---
> diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
> @@ -1,8 +1,12 @@
>  advice.*::
>         These variables control various optional help messages designed to
> -       aid new users.  When left unconfigured, Git will give the message
> -       alongside instructions on how to squelch it.  You can tell Git
> -       that you do not need the help message by setting these to `false`:
> +       aid new users. These are output to `stderr` by default as they are
> +       intended to help human readers. Tools that execute Git as a subprocess
> +       can disable these messages by setting `GIT_ACVICE=0` in the environment.

s/GIT_ACVICE/GIT_ADVICE/

gitgitgadget · 2024-09-05T18:05:54Z

User Eric Sunshine <[email protected]> has been added to the cc: list.

gitgitgadget · 2024-09-05T20:30:09Z

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Derrick Stolee via GitGitGadget" <[email protected]> writes:

>  advice.*::
>  	These variables control various optional help messages designed to
> -	aid new users.  When left unconfigured, Git will give the message
> -	alongside instructions on how to squelch it.  You can tell Git
> -	that you do not need the help message by setting these to `false`:
> +	aid new users. These are output to `stderr` by default as they are
> +	intended to help human readers. Tools that execute Git as a subprocess
> +	can disable these messages by setting `GIT_ACVICE=0` in the environment.
> ++
> +When left unconfigured, Git will give the message alongside instructions on how
> +to squelch it.  You can tell Git that you do not need the help message by
> +setting these to `false`:

This somehow makes it sounds like it is an "aside, by the way" that
these trigger by default and that you can selectively disable it by
setting these variables, but shouldn't the stress be the other way
around?  Shouldn't the mention of GIT_ADVICE be a side note, leaving
primary text target human users?

Perhaps like this?

Thanks.

 Documentation/config/advice.txt |  8 +++++++-
 Documentation/git.txt           | 11 +++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git c/Documentation/config/advice.txt w/Documentation/config/advice.txt
index 0ba8989820..d749aee7f4 100644
--- c/Documentation/config/advice.txt
+++ w/Documentation/config/advice.txt
@@ -2,7 +2,13 @@ advice.*::
 	These variables control various optional help messages designed to
 	aid new users.  When left unconfigured, Git will give the message
 	alongside instructions on how to squelch it.  You can tell Git
-	that you do not need the help message by setting these to `false`:
+	that you have understood the issue and no longer need a specific
+	help message by setting the corresponding variable to `false`.
++
+As they are intended to help human users, these messages are output
+to the standard error.  When tools that run Git as a subprocesses
+find them disruptive, they can set `GIT_ADVICE=0` in the environment
+to squelch all advice messages.
 +
 --
 	addEmbeddedRepo::
diff --git c/Documentation/git.txt w/Documentation/git.txt
index 4489e2297a..d15a869762 100644
--- c/Documentation/git.txt
+++ w/Documentation/git.txt
@@ -1027,6 +1027,17 @@ standard output.
 	adequate and support for it is likely to be removed in the
 	foreseeable future (along with the variable).
 
+`GIT_ADVICE`::
+	If set to `0`, then disable all advice messages. These messages are
+	intended to provide hints to human users that may help them get out of
+	problematic situations or take advantage of new features. Users can
+	disable individual messages using the `advice.*` config keys. These
+	messages may be disruptive to tools that execute Git processes, so this
+	variable is available to disable the messages. (The `--no-advice`
+	global option is also available, but old Git versions may fail when
+	this option is not understood. The environment variable will be ignored
+	by Git versions that do not understand it.)
+
 Discussion[[Discussion]]
 ------------------------

gitgitgadget · 2024-09-05T22:07:18Z

This patch series was integrated into seen via git@436747c.

The GIT_ADVICE environment variable was added implicitly in b79deeb (advice: add --no-advice global option, 2024-05-03) but was not documented. Add documentation to show that it is an option for tools that want to disable these messages. Make note that while the --no-advice option exists, older Git versions will fail to parse that option. The environment variable presents a way to change the behavior of Git versions that understand it without disrupting older versions. Co-authored-by: Junio C Hamano <[email protected]> Signed-off-by: Derrick Stolee <[email protected]>

gitgitgadget · 2024-09-06T19:49:54Z

On the Git mailing list, Derrick Stolee wrote (reply to this):

On 9/5/24 2:02 PM, Eric Sunshine wrote:
> On Thu, Sep 5, 2024 at 1:59 PM Derrick Stolee via GitGitGadget
> <[email protected]> wrote:
>> The GIT_ADVICE environment variable was added implicitly in b79deeb5544
>> (advice: add --no-advice global option, 2024-05-03) but was not
>> documented. Add documentation to show that it is an option for tools
>> that want to disable these messages. Make note that while the
>> --no-advice option exists, older Git versions will fail to parse that
>> option. The environment variable presents a way to change the behavior
>> of Git versions that understand it without disrupting older versions.
>>
>> Signed-off-by: Derrick Stolee <[email protected]>
>> ---
>> diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
>> @@ -1,8 +1,12 @@
>>   advice.*::
>>          These variables control various optional help messages designed to
>> -       aid new users.  When left unconfigured, Git will give the message
>> -       alongside instructions on how to squelch it.  You can tell Git
>> -       that you do not need the help message by setting these to `false`:
>> +       aid new users. These are output to `stderr` by default as they are
>> +       intended to help human readers. Tools that execute Git as a subprocess
>> +       can disable these messages by setting `GIT_ACVICE=0` in the environment.
> > s/GIT_ACVICE/GIT_ADVICE/

Thank you for catching my typo!
-Stolee

gitgitgadget · 2024-09-06T19:53:04Z

On the Git mailing list, Derrick Stolee wrote (reply to this):

On 9/5/24 4:26 PM, Junio C Hamano wrote:

> This somehow makes it sounds like it is an "aside, by the way" that
> these trigger by default and that you can selectively disable it by
> setting these variables, but shouldn't the stress be the other way
> around?  Shouldn't the mention of GIT_ADVICE be a side note, leaving
> primary text target human users?
> > Perhaps like this?
> > Thanks.
> >   Documentation/config/advice.txt |  8 +++++++-
>   Documentation/git.txt           | 11 +++++++++++
>   2 files changed, 18 insertions(+), 1 deletion(-)
> > diff --git c/Documentation/config/advice.txt w/Documentation/config/advice.txt
> index 0ba8989820..d749aee7f4 100644
> --- c/Documentation/config/advice.txt
> +++ w/Documentation/config/advice.txt
> @@ -2,7 +2,13 @@ advice.*::
>   	These variables control various optional help messages designed to
>   	aid new users.  When left unconfigured, Git will give the message
>   	alongside instructions on how to squelch it.  You can tell Git
> -	that you do not need the help message by setting these to `false`:
> +	that you have understood the issue and no longer need a specific
> +	help message by setting the corresponding variable to `false`.
> ++
> +As they are intended to help human users, these messages are output
> +to the standard error.  When tools that run Git as a subprocesses
> +find them disruptive, they can set `GIT_ADVICE=0` in the environment
> +to squelch all advice messages.
I like this a lot better. Your careful edit is substantial enough
that I will give you co-authored-by in v2.

Thanks,
-Stolee

derrickstolee · 2024-09-06T20:21:15Z

/submit

gitgitgadget · 2024-09-06T20:22:40Z

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1781/derrickstolee/advice-docs-v2

To fetch this version to local tag pr-1781/derrickstolee/advice-docs-v2:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1781/derrickstolee/advice-docs-v2

gitgitgadget · 2024-09-06T22:27:21Z

This patch series was integrated into seen via git@3a12ae9.

gitgitgadget · 2024-09-07T00:14:19Z

This patch series was integrated into seen via git@a6eb4d3.

gitgitgadget · 2024-09-07T17:42:16Z

This branch is now known as ds/doc-wholesale-disabling-advice-messages.

gitgitgadget · 2024-09-07T17:42:17Z

This patch series was integrated into seen via git@e785ff2.

gitgitgadget · 2024-09-07T17:42:17Z

This patch series was integrated into next via git@a52a31f.

gitgitgadget · 2024-09-09T02:42:32Z

There was a status update in the "New Topics" section about the branch ds/doc-wholesale-disabling-advice-messages on the Git mailing list:

The environment GIT_ADVICE has been intentionally kept undocumented
to discourage its use by interactive users.  Add documentation to
help tool writers.

Will merge to 'master'.
source: <[email protected]>

gitgitgadget · 2024-09-09T23:42:00Z

There was a status update in the "Cooking" section about the branch ds/doc-wholesale-disabling-advice-messages on the Git mailing list:

The environment GIT_ADVICE has been intentionally kept undocumented
to discourage its use by interactive users.  Add documentation to
help tool writers.

Will merge to 'master'.
source: <[email protected]>

gitgitgadget · 2024-09-10T21:15:29Z

This patch series was integrated into seen via git@3175465.

gitgitgadget · 2024-09-11T16:08:42Z

This patch series was integrated into seen via git@984b774.

gitgitgadget · 2024-09-12T20:54:33Z

This patch series was integrated into seen via git@dc2f0e9.

gitgitgadget · 2024-09-12T23:54:57Z

There was a status update in the "Cooking" section about the branch ds/doc-wholesale-disabling-advice-messages on the Git mailing list:

The environment GIT_ADVICE has been intentionally kept undocumented
to discourage its use by interactive users.  Add documentation to
help tool writers.

Will merge to 'master'.
source: <[email protected]>

gitgitgadget · 2024-09-13T20:57:15Z

This patch series was integrated into seen via git@3ae732c.

gitgitgadget · 2024-09-14T16:18:01Z

This patch series was integrated into seen via git@19de221.

gitgitgadget · 2024-09-14T16:18:01Z

This patch series was integrated into master via git@19de221.

gitgitgadget · 2024-09-14T16:18:02Z

This patch series was integrated into next via git@19de221.

gitgitgadget · 2024-09-14T16:18:04Z

Closed via 19de221.

derrickstolee self-assigned this Sep 5, 2024

derrickstolee force-pushed the advice-docs branch from 45e9439 to 52f6450 Compare September 5, 2024 15:55

derrickstolee force-pushed the advice-docs branch from 52f6450 to c13228d Compare September 5, 2024 18:55

gitgitgadget bot added the seen label Sep 5, 2024

derrickstolee force-pushed the advice-docs branch from c13228d to aacc8c0 Compare September 6, 2024 19:41

gitgitgadget bot added the next label Sep 7, 2024

gitgitgadget bot added the master label Sep 14, 2024

gitgitgadget bot closed this Sep 14, 2024

advice: recommend GIT_ADVICE=0 for tools #1781

advice: recommend GIT_ADVICE=0 for tools #1781

Uh oh!

Conversation

derrickstolee commented Sep 5, 2024 • edited by gitgitgadget bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

derrickstolee commented Sep 5, 2024

Uh oh!

gitgitgadget bot commented Sep 5, 2024

Uh oh!

gitgitgadget bot commented Sep 5, 2024

Uh oh!

gitgitgadget bot commented Sep 5, 2024

Uh oh!

gitgitgadget bot commented Sep 5, 2024

Uh oh!

gitgitgadget bot commented Sep 5, 2024

Uh oh!

gitgitgadget bot commented Sep 6, 2024

Uh oh!

gitgitgadget bot commented Sep 6, 2024

Uh oh!

derrickstolee commented Sep 6, 2024

Uh oh!

gitgitgadget bot commented Sep 6, 2024

Uh oh!

gitgitgadget bot commented Sep 6, 2024

Uh oh!

gitgitgadget bot commented Sep 7, 2024

Uh oh!

gitgitgadget bot commented Sep 7, 2024

Uh oh!

gitgitgadget bot commented Sep 7, 2024

Uh oh!

gitgitgadget bot commented Sep 7, 2024

Uh oh!

gitgitgadget bot commented Sep 9, 2024

Uh oh!

gitgitgadget bot commented Sep 9, 2024

Uh oh!

gitgitgadget bot commented Sep 10, 2024

Uh oh!

gitgitgadget bot commented Sep 11, 2024

Uh oh!

gitgitgadget bot commented Sep 12, 2024

Uh oh!

gitgitgadget bot commented Sep 12, 2024

Uh oh!

gitgitgadget bot commented Sep 13, 2024

Uh oh!

gitgitgadget bot commented Sep 14, 2024

Uh oh!

gitgitgadget bot commented Sep 14, 2024

Uh oh!

gitgitgadget bot commented Sep 14, 2024

Uh oh!

gitgitgadget bot commented Sep 14, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

derrickstolee commented Sep 5, 2024 •

edited by gitgitgadget bot

Loading